Implemented a standalone policy explanation engine for guild pass core - #404

Closes #369

Description

Implemented a standalone policy explanation engine for GuildPass Core that provides deterministic, structured explanations for policy evaluation decisions. The engine accepts a tree of evaluated policy conditions and produces explanations suitable for logs, tests, and access decisions without depending on membership persistence, API routes, or broader policy-engine implementations.

Linked Issue

Closes # (Add issue number when available)

Type of Change

• ✨ New feature / endpoint

Changes Made

• Created new package: @guildpass/policy-explanation - A standalone, side-effect-free explanation engine
• Implemented evaluation tree types: Strongly typed EvaluationNode discriminated union supporting ConditionNode, AllNode, AnyNode, and NotNode
• Built explanation engine: explainDecision() function that calculates outcomes, generates stable reason codes, and extracts relevant failing conditions
• Added validation: Enforces maximum depth (default: 50) and node-count (default: 1000) limits with safe rejection of malformed input via ExplanationError
• Implemented deterministic ordering: Sorts reasons by code and nodeId for consistent output across multiple calls
• Created utility functions: Builder functions (condition(), all(), any(), not()) and type guards for node types
• Wrote comprehensive tests: 51 unit tests covering nested structures, edge cases, validation, and side-effect verification

Test Evidence

pnpm --filter @guildpass/policy-explanation test

Expected output: 51 tests passing, 0 failures

Smart Contract Checklist (complete if ⛓️ checked above)

N/A - This is a TypeScript package, not a smart contract

General Checklist

• I have read CONTRIBUTING.md
• This PR is linked to an open issue
• npm run typecheck passes (or pnpm typecheck)
• npm run lint passes (N/A - no linting configured for this package)
• npm run test passes — all tests green (or pnpm test)
• Prisma schema changes include a migration file (N/A - no database changes)
• New API endpoints are documented in OpenAPI (N/A - this is a library package, not an API)
• No secrets, keys, or wallet addresses introduced
• .env.example updated if new env variables were added (N/A - no env variables)
• Documentation updated if new behaviour was introduced (comprehensive JSDoc comments in source)

Additional Notes

• Independence: This package is independently implementable and does not depend on the policy-expression evaluator, membership service, or access API
• No external dependencies: Pure TypeScript implementation with no database, Fastify, Redis, or HTTP dependencies
• Side-effect free: The engine does not modify input trees and produces independent results for each call
• TypeScript strict mode: Full type safety with discriminated unions and type guards
• Node.js native test runner: Uses node:test for testing without additional test framework dependencies